Subject: Comments to Jeff's final submission

From: [email-masked]
Date: Tue, 29 Nov 94 11:42:32 +0100

Here are some comments to Jeff's final submission:

General errors:

  - On page 10-12 change six times

	MAP_NAME,		/* local map name */
	MAP_NAME_LENGTH,	/* map name length */
    to
	unsigned char CM_PTR, 		/* local map name */
	CM_MAP_NAME_LENGTH CM_PTR,	/* map name length */

  - On page 20, line 14 change
	(TP-DATA request) UD-TRANSFER request
    to
	(TP-DATA request) U-ASE

  - On page 28, line 23 same change.

  - On page 54 move usage note 10 to number 8,
    move number 8 to number 9,
    move number 9 to number 10.

    (Reason: Usage notes 7 and 10 should be close together like in the
    original document.)

---------------------------------------------------------------------------

Problem number 1:

  Is a Send_Data call equal to a Send_Mapped_Data call with map_name_length=0
  and equal to using the CPI-C version 1.0 mapped conversation resp. the OSI
  UDT ASE?
  Is a Receive call equal to a Receive_Mapped_Data call with map_name_length=0
  and equal to using the CPI-C version 1.0 mapped conversation resp. the OSI
  UDT ASE?

  I interprete the paragraph beginning with the words "These calls could not"
  on page 3 of Jeff's document, that the answers to the 2 questions is yes.
  The second paragraph on page 1 says that a null map name is equal to using
  CPI-C version 1.0 mapped conversation resp. OSI UDT ASE. In addition the
  existing CPI-C document describes that Send_Data / Receive map to OSI UDT
  ASE.

  These 3 statements contradict to Jeff's last 2 emails:
  
  - A map routine is always used when doing mapped conversations - even today.
    This routine could be removed and a more sophisticated mechanism put in 
    its place that does more to the data stream. This is a method of taking
    existing CPI-C programs and allowing them to use different map routines
    as a very powerful means for allowing legacy programs to participate in
    new transactions without changing the application code.

  - If I send a Send_Mapped_Data (map_name_lenght=0) and my Receive_Mapped_Data
    does not have the CRM specific default map routine it will not be able to
    handle the data.

  I propose to define that a Send_Data call is equal to a Send_Mapped_Data 
  call with map_name_length=0 and equal to using the CPI-C version 1.0 
  mapped conversation resp. the OSI UDT ASE and that a Receive call is equal 
  to a Receive_Mapped_Data call with map_name_length=0 and equal to using 
  the CPI-C version 1.0 mapped conversation resp. the OSI UDT ASE.

  This results in the following change requests:

  - 	Change the second paragraph on page 1 to the following text:

	When an application program is moving data between homogeneous 
	systems and intends to perform all manipulation of data within 
	the application program itself, it may use the network like a
	pipe and simply send and receive buffers of data. The program
	can accomplish this by using pure Send_Data and Receive calls.
	It can also accomplish this by using Send_Mapped_Data and
	Receive_Mapped_Data calls not supplying a map name or supplying
	one with all blanks. The SNA routine is the vendor installed
	routine which supports CPI Communications version 1.0 mapped
	conversations. The OSI routine is the Unstructered Data Transfer
	U-ASE (UDT).

  - Change lines 12-20 on page 2 to the following text:

	Data sent with a Send_Data call can be received using Receive or
	Receive_Mapped_Data. Also data sent with a Send_Mapped_Data call
	(map_name_length=0) can be received using Receive or 
	Receive_Mapped_Data. Data sent with a Send_Mapped_Data call
	(map_name_lenght > 0) can be received only by using the
	Receive_Mapped_Data call.

---------------------------------------------------------------------------

Problem number 2:

  On the Receive_Mapped_Data, Receive_Mapped_Expedited_Data and
  Extract_Mapped_Initialization_Data, is the map name an input or
  output parameter?

  The Receive_Mapped_Expedited_Data describes map_name and map_name_length
  as output parameters, the Receive_Mapped_Data and Extract_Mapped_
  Initialization_Data describe them as input parameters. The text to
  the return code CM_UNKNOWN_MAP_NAME_RECEIVED on page 4 of Jeff's 
  document makes sense only if they are output parameters. The text of
  the parameter map_name_length on the 3 calls ("If zero, the map_name
  parameter is ignored.") makes sense only if the parameters are input
  parameters. So we have a lot of confusion.

  I propose to define them all as output parameters.

  This results in the following change requests:

  -	On pages 38, 42, 65 change the description of map_name and 
	map_name_lenght to the following text:

	map_name (output)
	Specifies the variable containing the mapping function used 
	to decode the data record. The length of the variable must be at 
	least 64 bytes.

	map_name_length (output)
	Specifies the variable containing the length of the returned
	map_name parameter.

---------------------------------------------------------------------------

Problem number 3:

  If conversation_type is set to CM_BASIC_CONVERSATION, should the new
  calls be allowed?

  Page 56 of Jeff's document describes that Send_Mapped_Data during a
  basic conversation results in an error. But I cannot find a return
  code for this case. 

  Usage note 19 of the Receive_Mapped_Data calls says that if a basic
  conversation record is received, it will be treated as an error by the
  map routine. I think this is an error in Jeff's document. If you look
  at a single data record, you probably cannot say whether this is a
  basic or mapped record. The basic conversation indicator is transported
  in the Attach Header, so a conversation can be basic or mapped, but not
  a data record.

  For technical reasons it may be possible to support map names in 
  initialization data and expedited data on a basic conversation, but
  for uniformeness I propose not to allow it.

  Therefore I propose to use the return code CM_PROGRAM_PARAMETER_CHECK
  if one of the 6 new calls is issued during a basic conversation.

  This results in the following change requests:

  - On pages 35, 40, 49, 50, 59, 61, 66, 69 add as additional reason 
    to CM_PROGRAM_PARAMETER_CHECK:

	The conversation_type characteristic is set to CM_BASIC_CONVERSATION.

  - On page 5 behind line 10:

	210 The conversation_type characteristic is set to 
	    CM_BASIC_CONVERSATION.

  - On page 54 delete usage note 19.

---------------------------------------------------------------------------

Problem number 4:

  Is the maximum_buffer_size (from the Extract_Maximum_Buffer_Size call)
  really the limit for a Send_Mapped_Data call?

  As Jeff describes, CPI-C products will be made in a way that users can
  add their own mapping routines to the product. Maximum buffer sizes are
  usually limitations of the CPI-C product, i.e. limits to the amount of
  data that can be sent after the work of the encoding routine. Maximum
  values of the send_length parameter of the Send_Mapped_Data call can
  be bigger or smaller. 
  In opposite to this, Jeff's document describes that the maximum buffer
  size is a limit to the send_length of the Send_Mapped_Data call.

  I propose to change the document, so that the maximum send_length
  depends on the mapping routine.

  This results in the following change requests:

  - On page 43 change lines 1-3 to the following text:

	the system and the map name. See usage note 10 on page xxx
	for additional information about determining the maximum
	buffer size.

  - On page 53 change usage note 9 (new number 10 according to my above
    change request) to the following text:

	A program must not specify a value in the requested_length parameter
	that is greater than the maximum the implementation can support. The
	maximum may vary from system to sytem. The maximum also depends
	on the map_name parameter. 

	Every CPI-C product must be able to receive data buffers with
	a length of 32767 bytes. Users who write map routines should
	describe the length of the data buffer after decoding if the
	encoded buffer has a length of 32767 bytes.

	The application program should use a requested_length value not
	smaller than this value. The program should also be aware that
	the CM_INCOMPLETE_DATA_RECEIVED value of the data_received
	parameter may be returned when the maximum buffer size differs 
	across the systems.

  - On page 55 delete the first paragraph.

  - On page 57 change the first sentence to

	The maximum buffer size depends on the map name. 

  - On page 57, line 2 change '9' to '6'.

  - On page 64, line 2 delete 'LU6.2', because this is also valid for
    an OSI TP CRM.

  - On page 59 delete the 2 sentences after 'The send_length exceeds
    the range permitted by the implementation.'

  - On page 64 change the second paragraph of usage note 4 to a new
    usage note 5. Change old usage note 5 to new number 6 and old
    number 6 to new number 7.

  - On page 54 change the usage note 5 (new number 6) to the following
    text:

	A program must not specify a value in the send_length parameter
	that is greater than the maximum the implementation can support.
	The maximum may vary from system to system. The maximum also
	depends on the map name parameter.

	Every CPI-C product must be able to send data buffers with
	a length of 32767 bytes. Users who write map routines should
	describe the length of the data buffer before encoding if the
	encoded buffer has a length of 32767 bytes.

	The application program should not use a send_lenth bigger 
	than this.

  - On page 64 delete the 4th paragraph of section 4.42.5.

  - Add the following text behind the usage note of the 
    Extract_Maximum_Buffer_Size call:

	For a mapped conversation with a non-null map name the largest amount
 	of data a program can send in a Send_Mapped_Data call and the largest
	amount of data that can be received by the program in a 
	Receive_Mapped_Data call depends on the map name.

---------------------------------------------------------------------------

Problem number 5:

  Can CPI-C support mapped initialization data and mapped expedited data
  on a LU6.2 CRM?

  I am not a LU6.2 expert. Jeff's document describes on page 19, that
  MC_ALLOCATE and MC_SEND_EXPEDITED_DATA do not support map names. So 
  I assume that LU6.2 does not support map names on PIP data and on
  expedited data. If this is true, I think, CPI-C should not support
  map names on initialization data and expedited data for an LU6.2 CRM.
  Since OSI TP does not suppport expedited data, this means to delete
  the calls Send_Mapped_Expedited_Data and Receive_Mapped_Expedited_Data.

  An alternative solution could be to define map_name and map_name_length
  as input parameters on the Send_Mapped_Expedited_Data, 
  Receive_Mapped_Expedited_Data, Set_Mapped_Initialization_Data,
  Extract_Mapped_Initialization_Data. In this case the application has
  to give the map name to the mapping routine. The application must
  know the name from other sources. But I don't like this solution,
  since it is hard to understand for users.

  Jeff writes in his document on page 19, that the map name on the
  Receive_Mapped_Expedited_Data should be derived locally by local
  means to identify what data it received. How should this work?
  If LU6.2 does not support map names on expedited data, CPI-C also
  should not do it.

  So I propose the following: Delete the Send_Mapped_Expedited_Data and
  Receive_Mapped_Expedited_Data, and support Set_Mapped_Initialization_Data
  and Extract_Mapped_Initialization_Data only for an OSI TP CRM.

Regards
Peter

-----------------------------------------------------------------------------
Peter Binninger                         Voice: (+49) 7531-87-4758
Computer Gesellschaft Konstanz mbH      Fax:   (+49) 7531-87-4888
(Siemens Nixdorf Informationssysteme)   Email: [email-masked]
Max-Stromeyer-Strasse 116
78467 Konstanz
Germany